Skip to main content

SSO Authentication

Flow​

Access token flow diagram

  1. When the application starts, authentication service provider identification is checked.
  2. The local storage of browser is checked to have a Refresh Token for the current user.
  3. If Refresh Token exists, Silent Token Update is performed to obtain a new Access Token.
  4. If Silent Token Update fails for any reason, the user will be logged out and redirected to a Login page.
  5. Application back-end uses auth provider to validate access tokens.

Basic Configuration​

This is the example of a common configuration for SSO authentication. Further in text, you can find examples of configurations for selected auth service providers.

# example of SSO common configuration
spring:
  security:
    oauth2:
      resourceserver:
        jwt:
          issuer-uri: <issuer uri>
security:
  oauth2:
    provider:
      providerType: SSO
      name: <name>
      clientId: <client id>
      audience: <audience>
      jwksUrl: <jwks url>
      configUrl: <config url>
      logoutUrl: <logout url>
      usernameClaim: <username claim>
      permissionsClaim: <permissions path claim>
      validateIssuer: <true|false>
      userInfo:
        enable: <true|false>
        userInfoUrl: <user info url>
        usernameKey: <list of username keys>
ParameterDescription
issuer-uriURI of the auth service provider.
nameName of the auth service provider.
clientIdEach connected application is given a personal ClientId from the provider.
audienceUnique identifier of the audience for an issued token, identified within a JSON Web Token as the audclaim. Each connected back-end (API) is given a personal audience from the auth provider. audience is always associated with a specific auth provider and may be optional with some providers.
jwksUrlURL of the authorization server's JWK Set document. The referenced document contains the signing key(s) the client uses to validate signatures from the authentication server.
configUrlStandard service provider endpoint.
logoutUrlStandard service provider logout URL.
usernameClaimUsername claim in token.
permissionsClaimAuthorities claim in token.
validateIssuerSet true to enable validation of auth provider URL in token against issuer-uri.
userInfo.enableSet true to enable user info URL by auth service provider.
userInfo.userInfoUrlURL with information about the user provided by the auth service provider.
userInfo.usernameKeyDefault usernames claims in token from auth service provider.

User Configuration​

Some SSO auth providers allow defining permissions for users and passing them in permissionsClaim.

info

Refer to Configuration to learn how to add or override the default configuration. 

# example of configuring user roles via permissions claim from auth provider
security:
  oauth2:
    provider:
      providerType: SSO
      name: <name>
      clientId: <client id>
      audience: <audience>
      jwksUrl: <jwks url>
      configUrl: <config url>
      logoutUrl: <logout url>
      usernameClaim: <username claim>
      permissionsClaim: <permissions path claim>

If your SSO auth provider does not support this, you can define permissions for users in application.yaml config in section users or in a JSON file. 

# example of how to define permissions for users for SSO authentication

security:
  oauth2:
    users:
      - username: <username>
        authorities: [TB_ALLOW_READ, TB_ALLOW_WRITE]
      - username: <username>
        authorities: [TB_ALLOW_READ]
...

Supported permissions:

  • TB_ALLOW_READ - user can select, view, get data stored in TimeBase streams.
  • TB_ALLOW_WRITE - user can write, modify, delete data stored in TimeBase streams.
  • GRAFANA - permission allowing Grafana plugin to query data from TimeBase.

You can combine permissions claim from auth provider and custom configurations in one config:

# example of a combination of permissionsClame and custom user configuration
security:
  oauth2:
    users:
      - username: <username>
        authorities: [TB_ALLOW_READ, TB_ALLOW_WRITE]
      - username: <username>
        authorities: [TB_ALLOW_READ]
    provider:
      providerType: SSO
      name: <name>
      clientId: <client id>
      audience: <audience>
      jwksUrl: <jwks url>
      configUrl: <config url>
      logoutUrl: <logout url>
      usernameClaim: <username claim>
      permissionsClaim: <permissions path claim>

Configuration Examples for Selected Auth Providers​

ORY Hydra​

To enable SSO with ORY Hydra, add the following blocks to your application.yaml configuration file. 

# example of configuration for ORY Hydra
spring:
  security:
    oauth2:
      resourceserver:
        jwt:
          issuer-uri: <service provider uri>

security:
  oauth2:
    provider:
      providerType: SSO
      name: hydra
      clientId: <client_id>
      validateIssuer: false
      userInfo:
        enable: true

Amazon Cognito​

To enable SSO with Amazon Cognito, add the following blocks to your application.yaml configuration file. 

# example of configuration for Amazon Cognito
spring:
  security:
    oauth2:
      resourceserver:
        jwt:
          issuer-uri: <service provider uri>

security:
  oauth2:
    provider:
      providerType: SSO
      name: cognito
      clientId: <client_id>
      audience: <audience>
      configUrl: <service provider config url>
      logoutUrl: <service provider logout url>
      usernameClaim: username
      validateIssuer: true

Keycloak​

To enable SSO with Keycloak, add the following blocks to your application.yaml configuration file. 

# example of configuration for Keycloak
spring:
  security:
    oauth2:
      resourceserver:
        jwt:
          issuer-uri: <service provider uri>

security:
  oauth2:
    provider:
      provider-type: SSO
      name: keycloak
      clientId: <client_id>
      usernameClaim: preferred_username
      validateIssuer: false
      validateClientId: true

Auth0​

To enable SSO with Auth0, add the following blocks to your application.yaml configuration file. 

# example of configuration for Auth0
spring:
  security:
    oauth2:
      resourceserver:
        jwt:
          issuer-uri: <service provider uri>

security:
  oauth2:
    provider:
      providerType: SSO
      name: auth0
      clientId: <client_id>
      audience: <audience url>
      configUrl: <configuration url>
      logoutUrl: <logout url>

Azure AD​

Azure AD App registration​

  1. Open Azure Portal.
  2. Find App registrations service.
  3. Choose New registration:
    1. Register a new application with Name (e.g. TB_WEBADMIN). Use default settings without Redirect URI.
    2. Navigate to Certificates & secrets for the created application and create a new client secret. We suggest saving it, because you will not be able to view it after it is created!
    3. Navigate to Expose an API for the created application and add an Application ID URI.
    4. Add a new scope on the same page (e.g. with the name app and display name app and any description) and set Who can consent? - Admins and users. The scope must be in the Enabled state.
  4. Return back to App registrations and use New registration again:
    1. Create the second application with a Name (e.g. TB_WEBADMIN_APP) with Redirect URI for the SPA.
    2. Navigate to Authentication page for created application and add new Redirect URI if you need. An example of Redirect URI list for localhost setup: http://localhost:8099/assets/sign-in.html http://localhost:8099/assets/silent-auth.html
    3. Navigate to API permissions and click Add a permission. Then, select the My APIs tab and select the application from p. 3.1 (TB_WEBADMIN). Find scope we created in p. 3.4 (app), choose it and click Add permission.
    4. Navigate to Overview and select the Endpoints tab. The endpoints from this tab will be used to configure Web Admin with Azure AD.

WebAdmin Configuration​

To enable SSO with Azure AD, add the following blocks to your application.yaml configuration file.

# example of configuration for Auth0
spring:
  security:
    oauth2:
      resourceserver:
        jwt:
          issuer-uri: <azure ad issuer uri> # for example, "https://login.microsoftonline.com/11111111-1111-1111-1111-1111111111111/v2.0"

security:
  oauth2:
    provider:
      providerType: SSO
      name: azure
      clientId: <Application (client) ID> # from Overview page of p.4.4, ex. 22222222-2222-2222-2222-222222222222
      validateIssuer: false
      usernameClaim: upn
      scopes:
        - openid
        - profile
        - <API Permission> # from p. 4.3 of Azure AD configuration, ex. api://333333333-3333-3333-33333-3333333333333/app

User Access Control with TimeBase Permissions​

Web Admin offers the capability to configure User Access Control (UAC) with permissions derived from the TimeBase server. Each user gets a unique connection to the TimeBase server and can only work with the streams they have permissions for.

Additionally, a "master connection" to TimeBase is created for executing system-level tasks such as processing views, metrics, etc.

Configuration​

To configure user access control with permissions from TimeBase:

  1. Configure TimeBase UAC with OAuth2 for a given authentication provider.

  2. Using the examples above, configure WebAdmin SSO UAC for the same authentication provider and add users.

  3. In the Web Admin's application.yaml file, configure authentication for the master connection to TimeBase:

    # example of TimeBase Master connection configuration for Azure AD:
    timebase:
      oauth2-client:
        url: https://login.microsoftonline.com/b41b72d0-4e9f-4c26-8a69-f949f367c91d/oauth2/v2.0/token
        client-id: 4d69eb9b-e7c3-4bf3-abc3-5c3ad64cb6fc
        client-secret: UlRzOFF+cXo0SW9pdlJXTU5TdVZBWEZ2OWtZTDhXZ0NDUExlMGFTMQ==
        scope: "api%3A%2F%2Ffcf8a41f-bf18-4229-8a2e-ec84d94df340%2F.default"

  4. In the same file, enable UAC with TimeBase permissions:

    timebase:
      enable-uac: true              # Enable TimeBase provided UAC

You can also configure the Web Admin to create a separate TimeBase connection for separate IPs:

timebase:
  uac:
    connection-per-ip: false    # Enable this

Configuration Example for Azure AD​

To configure user access control with TimeBase permissions for Azure AD:

  1. In the uac-oauth-security.xml file, configure TimeBase UAC by adding the users and client id taken from the Web Admin's master connection:

    <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
    <config xmlns="http://xml.deltixlab.com/internal/quantserver/3.0">
        <users>
            <!-- WebAdmin master connection user (client id) -->
            <user id="4d69eb9b-1111-1111-1111-5c3ad64cb6fd">
            </user>
            
            <!-- Users -->
            <user id="User@mail.com">
            </user>
        </users>
        <groups>
            <group id="Administrators">
                <!-- Add WebAdmin master connection user to Administrators group -->
                <principal>4d69eb9b-1111-1111-1111-5c3ad64cb6fd</principal>
            </group>
            <group id="Users">
                <principal>User@mail.com</principal>
            </group>
        </groups>
      <oauthSettings>
        <jwksUrl>https://login.microsoftonline.com/b41b72d0-1111-1111-1111-f949f367c91d/discovery/v2.0/keys</jwksUrl>
        <issuer>https://login.microsoftonline.com/b41b72d0-1111-1111-1111-f949f367c91d/v2.0</issuer>
            <!-- Same client id is used for WebAdmin master connection and users login -->
        <clientId>4d69eb9b-1111-1111-1111-5c3ad64cb6fd</clientId>
            <clientIdClaim>azp</clientIdClaim>
      </oauthSettings>
    </config>

  2. In application.yaml, configure the Web Admin by filling the issuer-uri, security, and timebase branches:

    ...
    # Add issuer
    spring:
      security:
        oauth2:
          resourceserver:
            jwt:
              issuer-uri: "https://login.microsoftonline.com/b41b72d0-1111-1111-1111-f949f367c91d/v2.0"
    ...
    timebase:
      url: dxtick://localhost:8011
      enable-uac: true    # Enable TimeBase provided UAC
      # Configure master connection
      oauth2-client:
        url: https://login.microsoftonline.com/b41b72d0-1111-1111-1111-f949f367c91d/oauth2/v2.0/token
        client-id: 4d69eb9b-1111-1111-1111-5c3ad64cb6fd
        client-secret: <client secret>
        scope: "api%3A%2F%2Ffcf8a41f-1111-1111-1111-ec84d94df341%2F.default"
    ...
    # Configure AzureAD SSO
    security:
      oauth2:
        provider:
          providerType: SSO
          name: azure
          clientId: 4d69eb9b-1111-1111-1111-5c3ad64cb6fd
          validateIssuer: false
          usernameClaim: preferred_username
          scopes:
            - openid
            - profile
            - api://fcf8a41f-1111-1111-1111-ec84d94df341/app
        users:
          - username: User@mail.com
            authorities: [TB_ALLOW_READ, TB_ALLOW_WRITE]
    ...